From fb05f97f8ef0e006dcc7159c05f99d240ef49585 Mon Sep 17 00:00:00 2001
From: "Karl O. Pinc kop@karlpinc.com" <kop@karlpinc.com>
Date: Wed, 5 Aug 2026 16:22:50 +0000
Subject: [PATCH] Add example query to MATINGS doc

---
 doc/src/tables/matings.m4 | 38 ++++++++++++++++++++++++++++++++++----
 1 file changed, 34 insertions(+), 4 deletions(-)

diff --git a/doc/src/tables/matings.m4 b/doc/src/tables/matings.m4
index 44dba27..1c63602 100644
--- a/doc/src/tables/matings.m4
+++ b/doc/src/tables/matings.m4
@@ -31,10 +31,6 @@ MATINGS
 
 |MATINGS_summary|
 
-.. sidebar::
-
-   |DYADS helpful|
-
 The related |EVENTS| row must be a mating event; it must have an
 |EVENTS|.\ |EVENTS.Behavior| value of ``sdb_mating_event``.
 This related |EVENTS| row supplies the time of the mating and
@@ -52,6 +48,40 @@ For further information, including additional data integrity rules,
 see the documentation of the :ref:`EVENTS <EVENTS_grooming_code>`
 table.
 
+The |DYADS| view is useful when querying MATINGS.
+
+.. code-block:: sql
+   :caption: Using DYADS to provide a more complete picture of matings
+
+   SELECT dyads.wid, dyads.type
+        , dyads.eid
+        , dyads.actor_pid, dyads.recipient_pid
+        , dyads.date
+        , dyads.animid AS focal
+        , dyads.commid AS watchescommid
+        , dyads.start AS time
+        , dyads.actor, dyads.recipient
+        , dyads.style
+        , matings.swelling
+        , matings.fail
+        , matings.interference
+        , matings.incest
+        , matings.consort
+        , matings.guarding
+        , matings.courting
+        , matings.camp
+        , matings.commid AS matingscommid
+        , matings.extractedby
+        , matings.source
+        , dyads.notes
+        , dyads.event_notes
+     FROM dyads
+       JOIN matings
+            ON (matings.eid = dyads.eid)
+     WHERE dyads.behavior = 'sdb_mating_event'
+     ORDER BY dyads.actor, dyads.date, dyads.start
+            , dyads.recipient, dyads.eid;
+
 
 .. contents::
    :depth: 2
-- 
2.34.1